package edu.gmu.streams;

import java.io.IOException;

/**
 * A BlockOutputStream writes primitive Java numbers
 * and characters to an output stream.  Byte-order is determined
 * by the particular implementation.
 * <p>
 * This interface differs from DataOutput in that it also
 * provides efficient methods for writing primitive arrays out.
 *
 * @author  James H. Pope
 * @version $Revision:$ $Date:$
 */
public interface BlockOutputStream
{
    /**
     * Skips the number of bytes ahead as indicated.
     * @param num bytes to skip
     */
    public void skipBytes(int skip) throws IOException;
    
    /**
     * Writes byte from underlying stream.
     * @param b
     * @throws java.io.IOException
     */
    public void writeByte( byte b ) throws IOException;
    
    /**
     * Writes boolean (1-byte) to underlying stream.
     * @param b
     * @throws java.io.IOException
     */
    public void writeBoolean( boolean b ) throws IOException;
    
    /**
     * Writes short to underlying stream as two bytes.
     * @param s
     * @throws java.io.IOException
     */
    public void writeShort( short s ) throws IOException;
    
    /**
     * Writes short to underlying stream as four bytes.
     * @param i
     * @throws java.io.IOException
     */
    public void writeInt( int i ) throws IOException;
    
    /**
     * Writes short to underlying stream as eight bytes.
     * @param l
     * @throws java.io.IOException
     */
    public void writeLong( long l ) throws IOException;
    
    /**
     * Writes short to underlying stream as four bytes.
     * @param f
     * @throws java.io.IOException
     */
    public void writeFloat( float f ) throws IOException;
    
    /**
     * Writes short to underlying stream as eight bytes.
     * @param d
     * @throws java.io.IOException
     */
    public void writeDouble( double d ) throws IOException;
    
    /**
     * Writes variable length (2-byte length header) of UTF characters to
     * the underlying stream. 
     * @param String
     * @throws java.io.IOException
     */
    public void writeUTF( String s ) throws IOException;
    
    
    /**
     * Bulk transfers bytes from given array to this buffer.
     * @param bytes
     * @throws java.io.IOException
     */
    public void write( byte[] bytes ) throws IOException;
    
    /**
     * Bulk transfers booleans from given array to this buffer.
     * Implemenations may fall back to loop-calling writeBoolean().
     * @param booleans
     * @throws java.io.IOException
     */
    public void write( boolean[] booleans ) throws IOException;
    
    /**
     * Bulk transfers shorts from given array to this buffer.
     * @param shorts
     * @throws java.io.IOException
     */
    public void write( short[] shorts ) throws IOException;
    
    /**
     * Bulk transfers integers from given array to this buffer.
     * @param integers
     * @throws java.io.IOException
     */
    public void write( int[] integers ) throws IOException;
  
    /**
     * Bulk transfers floats from given array to this buffer.
     * @param floats
     * @throws java.io.IOException
     */
    public void write( float[] floats ) throws IOException;
    
    /**
     * Bulk transfers longs from given array to this buffer.
     * @param longs
     * @throws java.io.IOException
     */
    public void write( long[] longs ) throws IOException;
    
    /**
     * Bulk transfers doubles from given array to this buffer.
     * @param doubles
     * @throws java.io.IOException
     */
    public void write( double[] doubles ) throws IOException;
    
    /**
     * Bulk transfers strings from given array to this buffer.
     * Implemenations may fall back to loop-calling writeUTF().
     * @param strings
     * @throws java.io.IOException
     */
    public void write( String[] strings ) throws IOException;
}
